Dashboard Widget

When embedded in an application, the Dashboard widget enables complete dashboard management for tenant end-users.

⚡ Quick Embeddable Sample (For Testing Only)

Important: This example is for testing purposes only.

• In production, you must use a qvToken instead of exposing an apiKey in the UI.
• The apiKey is private and should only be used for communication between backends.
• For testing, clientId can match the userId. In production, the clientId requires a unique identifier for each tenant end user.

<!-- Tag -->
<qrvey-dashboard settings="dashboardConfig"></qrvey-dashboard>

<!-- Config -->
<script>
var dashboardConfig = {   
   "apiKey": "<YOUR_PRIVATE_API_KEY>",   // Testing only. Do not use in production UI.
   "domain": "<DOMAIN>",   
   "appId":  "<APP_ID>", 
   "userId": "<USER_ID>",
   "dashboardId": "<DASHBOARD_ID>",
   "clientId": "<CLIENT_ID>",            // Optional, for testing, this can match userId.
   "orgId": "org:0"                      // Optional, for testing, use org:0 (base organization)
};  
</script>

<!-- Launcher -->
<script type="module" src="https://<DOMAIN>/qrvey-dashboard/qrvey-dashboard/qrvey-dashboard.esm.js"></script>

Production Deployment

• Use qvToken instead of apiKey.
• Pass sensitive values (appId, userId, clientId, orgId) using the qvToken, not in a plain configuration.
• In production, configure roles, orgs, filters, i18n, and theme as needed.

Configuration Object

Property	Type	Required	QVToken Support	Description
domain	String	Yes	No	Qrvey instance URL.
qvToken	String	No	No	Encrypted string securing the widget configuration. Required if no apiKey is provided. This string cannot be used with apiKey.
apiKey	String	Yes, if qvToken is not provided	No	Secret identification token for accessing the application. Required if qvToken is not provided. This string cannot be used with qvToken.
appId	String	Yes	Yes	ID of the Qrvey application. Must be passed using qvToken in production.
userId	String	No	Yes	User ID of the application owner. Must be passed using qvToken in production.
dashboardId	String	No	Yes	ID of a specific dashboard to embed. If omitted, the widget display the "browse dashboards" page.
clientId	String	No	Yes. Must be passed using qvToken during production.	Unique identifier for the tenant end user. - Used for testing, this can match the userId. - In production, each tenant requires a unique value. Pass the value using qvToken. If omitted, the widget assumes anonymous.
roles	Array(String)	No	Only	Used for Column Level Security.
orgId	String	No	Yes	Organization ID for the end user. Used for asset ownership. If omitted, widget uses the clientId's orgId (if set in orgs object). Otherwise, use anonymous.
orgs	Array(Object)	No	Only	Orgs object to list users, defined per organization, in the Subscribe modal. Note: The orgs object is ignored when the widget's orgId is set to org:0.
userFilters	Object	No	Yes	Collection of custom filters that the system applies to the visualized data. For more information, see Working With Filters in Embedded Scenarios.
timezone	String	No	Yes	Timezone offset applied to dates. For more information, see Configuring Time Zone Settings.
i18n	Object	No	No	Defines language and localization. For more information, see i18n Object.
themeId	String	No	No	Theme ID to use in the component. For more information, see Accessing a Theme Programmatically.
styles	JSON	No	No	Key-value JSON with style variables. For more information, see Dashboard Styles.
defaultMode	"design" or "interact"	No	No	Sets the dashboard's default mode to open in design or interact mode. Defaults to interact mode. Only applies to a single dashboard.
customTokens	Custom tokens	No	No	Sets custom tokens. For more information, see Using Custom Tokens.
permissions	JSON	No	Only	Record-level security permissions object.
asset_permissions	Asset permissions	No	Only	The asset permissions object.
email	String	No	Only	Email of the clientId user. Required to enable scheduling and subscription. Pass this property in qvToken.
customization	JSON	No	No	The Dashboard customization object.

Orgs

For an overview of organizations, see Organizations, Ownership, and Subscriptions

Property	Type	Description
orgId	String	ID of the organization to which the roles and users will be defined next. Should correspond to the user in session's orgId if you want the roles and users to be listed in subscribe.
users	Array	Object/array of users to be listed in the subscribe modal. This is not for the current user. Adjust clientId and email accordingly.
users.clientId	String	Client ID of the user.
users.email	String	Email address of the user.

Example

const orgs = [
  {
      orgId: 'ORG_ID',
      users: [
        {
          clientId: 'CLIENT_ID',
          email: 'EMAIL'
        },
        {
          clientId: 'CLIENT_ID2',
          email: 'EMAIL2'
        }
      ]
  }
]

i18n

For more information, see Internationalization, Step by Step.

Property	Type	Required	Value
lang	String	Yes	Language to use for the UI. Example: "es".
locale	String	No	Locale code to use for date and number formatting. Example: "es-ES".

Styles

The Dashboard Widget supports customization through CSS variables, allowing you to adapt the look and feel of dashboards to match your application’s design system. This includes control over fonts, colors, spacing, and other UI elements.

By overriding the available style variables, you can achieve a fully branded experience for end users without altering functionality. This is the recommended way to ensure consistency across embedded dashboards.

For the complete list of available style variables and examples of how to use them, see Styles.

Methods and Events

The Dashboard widget supports the following interaction patterns:

• Direct Method Calls - Uses the executeAction method.
• Event-Based Communication - Uses custom events with promise-based responses.

Both approaches provide the same functionality with different implementation styles, allowing developers to programmatically control dashboard behavior (such as applying filters, switching versions, or triggering downloads) from their host application and integrate dashboard actions into their own UI workflows or automation scripts.

For the complete list of available style variables and examples of how to use them, see Methods and Events.